home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / library / help / tcl / libraries / library < prev    next >
Encoding:
Text File  |  1993-10-26  |  9.4 KB  |  189 lines  |  [TEXT/$Tcl]
  1.  
  2.           auto_execok cmd
  3.           auto_load cmd
  4.           auto_mkindex dir pattern pattern ...
  5.           auto_reset
  6.           parray arrayName
  7.           unknown cmd ?arg arg ...?
  8.  
  9.  
  10.      INTRODUCTION
  11.           Tcl includes a library of Tcl procedures for commonly-needed
  12.           functions.   The  procedures  defined in the Tcl library are
  13.           generic ones suitable for use  by  many  different  applica-
  14.           tions.   The  location of the Tcl library is returned by the
  15.           info library command.  In addition to the Tcl library,  each
  16.           application  will  normally  have its own library of support
  17.           procedures as well;  the location of this  library  is  nor-
  18.           mally  given  by  the value of the $app_library global vari-
  19.           able, where app is the name of the application.   For  exam-
  20.           ple,  the location of the Tk library is kept in the variable
  21.           $tk_library.
  22.  
  23.           To access the procedures in the Tcl library, an  application
  24.           should  source the file init.tcl in the library, for example
  25.           with the Tcl command
  26.  
  27.                source [info library]/init.tcl
  28.  
  29.           This will define the unknown procedure and arrange  for  the
  30.           other  procedures to be loaded on-demand using the auto-load
  31.           mechanism defined below.
  32.  
  33.  
  34.      COMMAND PROCEDURES
  35.           The following procedures are provided in the Tcl library:
  36.  
  37.           auto_execok cmd
  38.                Determines whether there is an executable file  by  the
  39.                name cmd.  This command examines the directories in the
  40.                current search path  (given  by  the  PATH  enviornment
  41.                variable)  to  see if there is an executable file named
  42.                cmd in any of those directories.  If so, it returns  1;
  43.                if  not  it returns 0.  Auto_exec remembers information
  44.                about previous searches in an array  named  auto_execs;
  45.                this  avoids  the  path  search in future calls for the
  46.                same cmd.  The command auto_reset may be used to  force
  47.                auto_execok to forget its cached information.
  48.  
  49.           auto_load cmd
  50.                This command attempts to load the definition for a  Tcl
  51.                command  named  cmd.   To do this, it searches an auto-
  52.                load path, which is a list of one or more  directories.
  53.                The  auto-load  path  is  given  by the global variable
  54.                $auto_path if it exists.  If  there  is  no  $auto_path
  55.                variable,  then  the TCLLIBPATH environment variable is
  56.                used, if it exists.  Otherwise the auto-load path  con-
  57.                sists  of  just the Tcl library directory.  Within each
  58.                directory in the auto-load path there must  be  a  file
  59.                tclIndex that describes one or more commands defined in
  60.                that directory and a script to evaluate to load each of
  61.                the  commands.   The  tclIndex file should be generated
  62.                with the auto_mkindex command.  If cmd is found  in  an
  63.                index file, then the appropriate script is evaluated to
  64.                create the command.  The auto_load command returns 1 if
  65.                cmd was successfully created.  The command returns 0 if
  66.                there was no index entry  for  cmd  or  if  the  script
  67.                didn't   actually   define   cmd  (e.g.  because  index
  68.                information is out of date).  If an error occurs  while
  69.                processing  the  script,  then  that error is returned.
  70.                Auto_load only reads the  index  information  once  and
  71.                saves  it  in  the  array  auto_index;  future calls to
  72.                auto_load check for cmd in the array  rather  than  re-
  73.                reading  the index files.  The cached index information
  74.                may be deleted with the command auto_reset.  This  will
  75.                force  the  next  auto_load command to reload the index
  76.                database from disk.
  77.  
  78.           auto_mkindex dir pattern pattern ...
  79.                Generates an index suitable for use by auto_load.   The
  80.                command  searches  dir  for all files whose names match
  81.                any of the pattern arguments (matching is done with the
  82.                glob  command),  generates an index of all the Tcl com-
  83.                mand procedures defined in all the matching files,  and
  84.                stores  the  index information in a file named tclIndex
  85.                in dir.  For example, the command
  86.  
  87.                     auto_mkindex foo *.tcl
  88.  
  89.                will read all the .tcl files in  subdirectory  foo  and
  90.                generate a new index file foo/tclIndex.
  91.  
  92.                Auto_mkindex parses the Tcl  scripts  in  a  relatively
  93.                unsophisticated  way:   if  any  line contains the word
  94.                proc as its first characters then it is assumed to be a
  95.                procedure  definition  and the next word of the line is
  96.                taken as the procedure's name.   Procedure  definitions
  97.                that  don't  appear  in this way (e.g. they have spaces
  98.                before the proc) will not be indexed.
  99.  
  100.           auto_reset
  101.                Destroys all the information cached by auto_execok  and
  102.                auto_load.   This information will be re-read from disk
  103.                the next time it is needed.   Auto_reset  also  deletes
  104.                any  procedures  listed in the auto-load index, so that
  105.                fresh copies of them will be loaded the next time  that
  106.                they're used.
  107.  
  108.           parray arrayName
  109.                Prints on standard output the names and values  of  all
  110.                the elements in the array arrayName.  ArrayName must be
  111.                an array accessible to the caller of parray.  It may be
  112.                either local or global.
  113.  
  114.           unknown cmd ?arg arg ...?
  115.                This procedure is  invoked  automatically  by  the  Tcl
  116.                interpreter  whenever  the  name  of  a command doesn't
  117.                exist.  The unknown procedure receives as its arguments
  118.                the name and arguments of the missing command.  Unknown
  119.                first calls auto_load to load  the  command.   If  this
  120.                succeeds,  then  it  executes the original command with
  121.                its original arguments.  If the  auto-load  fails  then
  122.                unknown calls auto_execok to see if there is an execut-
  123.                able file by the name cmd.  If so, it invokes  the  Tcl
  124.                exec  command  with  cmd and all the args as arguments.
  125.                If cmd can't be auto-executed, unknown checks to see if
  126.                the command was invoked at top-level and outside of any
  127.                script.  If so, then unknown takes takes two additional
  128.                steps.   First, it sees if cmd has one of the following
  129.                three forms: !!, !event, or ^old^new?^?.  If  so,  then
  130.                unknown  carries  out  history substitution in the same
  131.                way that csh would for these constructs.   Second,  and
  132.                last, unknown checks to see if cmd is a unique abbrevi-
  133.                ation for an existing Tcl command.  If so,  it  expands
  134.                the command name and executes the command with the ori-
  135.                ginal arguments.  If none of the above efforts has been
  136.                able to execute the command, unknown generates an error
  137.                return.  If the global variable auto_noload is defined,
  138.                then  the  auto-load  step  is  skipped.  If the global
  139.                variable auto_noexec is defined then the auto-exec step
  140.                is  skipped.   Under  normal  circumstances  the return
  141.                value from unknown is the return value from the command
  142.                that was eventually executed.
  143.  
  144.  
  145.      VARIABLES
  146.           The following global variables are defined or  used  by  the
  147.           procedures in the Tcl library:
  148.  
  149.           auto_execs
  150.                Used by auto_execok to record information about whether
  151.                particular commands exist as executable files.
  152.  
  153.           auto_index
  154.                Used by auto_load to save the  index  information  read
  155.                from disk.
  156.  
  157.           auto_noexec
  158.                If set to any value, then unknown will not  attempt  to
  159.                auto-exec any commands.
  160.  
  161.           auto_noload
  162.                If set to any value, then unknown will not  attempt  to
  163.                auto-load any commands.
  164.  
  165.           auto_path
  166.                If set, then it must contain a valid  Tcl  list  giving
  167.                directories to search during auto-load operations.
  168.  
  169.           env(TCL_LIBRARY)
  170.                If set, then it specifies the location of the directory
  171.                containing  library scripts (the value of this variable
  172.                will be returned by the command info library).  If this
  173.                variable isn't set then a default value is used.
  174.  
  175.           env(TCLLIBPATH)
  176.                If set, then it must contain a valid  Tcl  list  giving
  177.                directories  to  search  during  auto-load  operations.
  178.                This variable is only used if auto_path is not defined.
  179.  
  180.           unknown_active
  181.                This variable is set by unknown to indicate that it  is
  182.                active.   It  is  used  to  detect errors where unknown
  183.                recurses on itself infinitely.  The variable  is  unset
  184.                before unknown returns.
  185.  
  186.  
  187.      KEYWORDS
  188.           auto-exec, auto-load, library, unknown
  189.